feat: attach AI reasoning as a comment on approval requests#1733
Merged
Conversation
…ests When an AI triggers an approval-gated custom action (via the MCP executeAction tool or the workflow-executor trigger-action step), the created approval request now carries the AI's reasoning as a comment so the approver understands why it was triggered. - agent-client: Action.execute() accepts an optional message; the approval request creator posts it to /api/action-approvals/:id/comments (best-effort). - mcp-server: executeAction exposes an optional `reasoning` field forwarded to the approval request. - workflow-executor: the trigger-action step captures the AI action-selection reasoning (previously discarded), falling back to the step prompt, and threads it through as approvalMessage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 new issue
|
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
|
Coverage Impact This PR will not change total coverage. Modified Files with Diff Coverage (5)
🛟 Help
|
…ss review - Action.execute now takes an ActionExecuteOptions object instead of two positional optionals (signedApprovalRequest, approvalRequestMessage). - approval-request-creator: bind and warn on a failed comment POST instead of a bare silent catch (keeps best-effort semantics). - Add tests for the AI-empty-reasoning → step.prompt fallback and the no-message-omitted path in the trigger-action executor. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…threading Keep only the non-obvious rationale (best-effort comment post, comment destination, prompt fallback); drop comments that restate self-documenting names. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
christophebrun-forest
approved these changes
Jul 3, 2026
christophebrun-forest
left a comment
christophebrun-forest
left a comment
Member
There was a problem hiding this comment.
Manual test OK
LGTM
forest-bot
added a commit
that referenced
this pull request
Jul 3, 2026
# @forestadmin/agent-client [1.10.0](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.9.0...@forestadmin/agent-client@1.10.0) (2026-07-03) ### Features * attach AI reasoning as a comment on approval requests ([#1733](#1733)) ([bb6ee3f](bb6ee3f))
forest-bot
added a commit
that referenced
this pull request
Jul 3, 2026
# @forestadmin/mcp-server [1.16.0](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/mcp-server@1.15.1...@forestadmin/mcp-server@1.16.0) (2026-07-03) ### Features * attach AI reasoning as a comment on approval requests ([#1733](#1733)) ([bb6ee3f](bb6ee3f)) ### Dependencies * **@forestadmin/agent-client:** upgraded to 1.10.0
forest-bot
added a commit
that referenced
this pull request
Jul 3, 2026
# @forestadmin/workflow-executor [1.13.0](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/workflow-executor@1.12.0...@forestadmin/workflow-executor@1.13.0) (2026-07-03) ### Features * attach AI reasoning as a comment on approval requests ([#1733](#1733)) ([bb6ee3f](bb6ee3f)) ### Dependencies * **@forestadmin/agent-client:** upgraded to 1.10.0
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
When an AI triggers a custom action that requires approval — via the MCP
executeActiontool or the workflow-executortrigger-actionstep — the created approval request carried no explanation. The approver saw a bare request with no idea why the AI triggered it.This PR lets the AI attach its reasoning, surfaced as a comment on the approval request.
Why a comment (not an attribute)
Checked the Forest server (
forestadmin-server):POST /api/action-approvalsonly validatesstatus / action_name / collection_name / record_ids / inputs— any extra attribute is dropped, and theactionApprovalmodel has no message field. The free-text channel is the dedicatedactionApprovalCommentresource (POST /api/action-approvals/:id/comments,data.attributes.comment), same auth stack as creation. So the message is posted there.Changes
Action.execute(signedApprovalRequest?, approvalRequestMessage?)forwards an optional message.makeCreateApprovalRequestposts the message to/api/action-approvals/:id/commentsafter the approval is created — best-effort: a comment failure never turns the successful approval into an error.executeActionexposes an optionalreasoningfield (LLM-facing description asks it to always explain why), forwarded toexecute(). Covers direct MCP use and the workflowmcpstep.trigger-actionstep captures the AI action-selectionreasoning(previously discarded inselectAction), falling back to the step prompt for pre-recorded actions, and threads it throughExecuteActionQuery.approvalMessage. Reasoning stays out ofStepOutcome(privacy invariant preserved).Tests
reasoningforwarded toexecute().approvalMessagetransmitted to the port; AI reasoning captured; prompt fallback for pre-recorded actions.All suites green (agent-client 344, mcp-server 548, workflow-executor 1155), builds + lint clean.
Verification
Verified end-to-end against a local agent + Forest server: triggering the approval-gated
Create new cardaction via MCP with areasoningcreates the approval request with the reasoning shown as a comment in the front. 🤖 Generated with Claude CodeNote
Attach AI reasoning as a comment on approval requests
Action.executein action.ts now accepts an options object with an optionalapprovalRequestMessage; after creating the approval request, a follow-up POST is made to/api/action-approvals/{id}/comments.executeActiontool gains an optionalreasoninginput field that is forwarded through to the approval request comment.TriggerRecordActionStepExecutorderives the approval message from the AI selection's reasoning, falling back to the step prompt, and omits the message if neither is available.console.warnand do not affect the approval request result. Callers previously passing a baresignedApprovalRequesttoAction.executemust now wrap it in an options object.Macroscope summarized 787b9be.